/*
 * Copyright 2007-2009 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.paoding.rose.web.impl.module;

import java.util.List;

import net.paoding.rose.web.ControllerErrorHandler;

import org.springframework.web.multipart.MultipartResolver;

/**
 * {@link Module}代表了在同一个web程序中的一个模块。不同的模块包含一些特定的控制器对象、控制器拦截器、控制器异常处理器。
 * 不同的模块共享了ServletContext以及整个程序的中间层、资源层。
 * <p>
 * 一个web程序的不同的模块有不同的名字和路径。作为{@link Module}接口本身并没有要求模块的名字和路径有什么关系，
 * 但在实现上模块的路径是由其名字决定的，即path=/name，比如名字为admin的模块，路径将是/admin。
 * 作为一个特例，名字为root的模块路径则只是空串。
 * <p>
 * 一个HTTP请求将根据它的URI，映射到相应的web程序中(由web容器处理)，而后又映射给具体的module模块(由Rose处理)。
 * 映射规则以模块的路径为依据(名字此时不参与这个决策)。
 * <p>
 * 
 * 
 * @author qieqie.wang@paoding.net
 * 
 */
public interface Module extends Comparable<Module> {

	/**
	 * 该module负责的请求的URL(context path剔除外)的起始地址
	 * 
	 * @return
	 */
	public String getPath();

	/**
	 * 当URI没有指明控制器名时，默认使用哪个控制器？
	 * 
	 * @return
	 */
	public String getDefaultControllerPath();

	/**
	 * 该module下所具有的controller映射地址，这将在根据URI dispatch控制器的时候被用上
	 * 
	 * @return
	 */
	public List<String> getControllerPaths();

	/**
	 * 返回指定控制器名字对应的控制器处理类
	 * <p>
	 * Rose v1将在初始化该框架的时候就把所有controller初始化在容器中，所以请注意controller不能把request-
	 * scope的变量放到controller类中作为field变量
	 * 
	 * @param controllerName
	 * @return
	 * @see #getControllerPaths()
	 */
	public Object getController(String controllerPath);

	/**
	 * 返回控制器的Class类。因为代码增强的原因，他不总是=controller.getClass()
	 * 
	 * @param controllerName
	 * @return
	 */
	public Class<?> getControllerClass(String controllerPath);

	/**
	 * 返回本module所使用的拦截器。
	 * 
	 * @return
	 */
	public NamedControllerInterceptor[] getInterceptors();

	/**
	 * 该模块的异常处理类，这个异常处理类处理的是控制器抛出的异常，开发者可以利用这个特性记录控制器抛出的异常并重新返回一个友好的页面给用户
	 * 
	 * @return
	 */
	public ControllerErrorHandler getErrorHandler();

	/**
	 * 
	 * @return
	 */
	public MultipartResolver getMultipartResolver();

}
